feat(client): add reconnectionScheduler to StreamableHTTPClientTransport by felixweinberger · Pull Request #1763 · modelcontextprotocol/typescript-sdk

felixweinberger · 2026-03-25T21:26:49Z

Adds a ReconnectionScheduler callback option to StreamableHTTPClientTransportOptions so non-persistent environments can override the default setTimeout-based SSE reconnection scheduling.

Motivation and Context

Fixes #1162. The current _scheduleReconnection uses setTimeout, which doesn't work well for:

Serverless/edge functions that terminate before the timer fires
Mobile apps that need platform-specific background scheduling (iOS Background Fetch, Android WorkManager)
Desktop apps handling sleep/wake cycles

Supersedes #1177 with one API addition: the scheduler may return a cancel function that is invoked on transport.close(), so pending custom-scheduled reconnections can be aborted the same way the built-in setTimeout is cleared. Thanks @CHOIJEWON for the original implementation.

How Has This Been Tested?

6 new tests in packages/client/test/client/streamableHttp.test.ts:

scheduler invoked with (reconnect, delay, attemptCount)
falls back to setTimeout when no scheduler provided
setTimeout not used when scheduler provided
returned cancel function called on close()
tolerates schedulers returning void (no cancel)
default setTimeout still cleared on close()

pnpm --filter @modelcontextprotocol/client test passes (317 tests).

Breaking Changes

None. New optional option, default behavior unchanged. Internal _reconnectionTimeout field renamed to _cancelReconnection (private, not part of public API).

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

API:

type ReconnectionScheduler = (
    reconnect: () => void,
    delay: number,
    attemptCount: number
) => (() => void) | void;

The _reconnectionTimeout?: ReturnType<typeof setTimeout> field is replaced by _cancelReconnection?: () => void, unifying cleanup for both the default and custom scheduler paths.

Adds a ReconnectionScheduler callback option so non-persistent environments can override the default setTimeout-based SSE reconnection scheduling. The scheduler receives (reconnect, delay, attemptCount) and may return a cancel function that is invoked on transport.close(). This ensures pending custom-scheduled reconnections can be aborted the same way the built-in setTimeout is cleared. Replaces the _reconnectionTimeout field with a unified _cancelReconnection callback that works for both the default and custom scheduler paths. Fixes #1162 Closes #1177 Co-authored-by: CHOIJEWON <alsrn6040@kakao.com>

changeset-bot · 2026-03-25T21:26:59Z

🦋 Changeset detected

Latest commit: 6e24e54

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/client	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-03-25T21:28:17Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1763

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1763

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1763

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1763

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1763

commit: 6e24e54

claude

LGTM — clean, minimal API addition with good test coverage and no change to default behavior.

Extended reasoning...

Overview

This PR adds a single optional reconnectionScheduler callback to StreamableHTTPClientTransportOptions, allowing non-persistent environments (serverless, mobile, desktop sleep/wake) to override the default setTimeout-based SSE reconnection. The implementation touches one source file (streamableHttp.ts) and its test file, plus a changeset. The internal _reconnectionTimeout field is replaced by a unified _cancelReconnection callback that works for both the default setTimeout path and custom schedulers.

Security risks

None. The change is a scheduling mechanism for reconnection — it does not touch auth, credentials, permissions, or data handling. The scheduler callback receives only a reconnect function, a delay number, and an attempt count.

Level of scrutiny

Low-to-moderate. This is a new optional configuration option with no change to default behavior. The API surface is small (ReconnectionScheduler type + one optional property). The refactoring from _reconnectionTimeout to _cancelReconnection is purely internal (private fields). The implementation correctly handles void returns from the scheduler, clears _cancelReconnection before invoking reconnect(), and the close() method properly calls and nullifies the cancel function.

Other factors

6 new focused tests cover: scheduler invocation with correct arguments, setTimeout fallback, cancel-on-close, void-tolerant schedulers, and clearTimeout on close without a scheduler.
2 existing tests were updated to reference the renamed private field (_cancelReconnection instead of _reconnectionTimeout).
No CODEOWNERS-specific paths are affected beyond the default wildcard.
The changeset correctly marks this as a minor version bump.
No outstanding reviewer comments or unaddressed feedback in the timeline.

felixweinberger · 2026-03-25T21:36:49Z

Picked this up as something we discussed previously @mattzcarey

bhosmer-ant

Nice feature — the API design is clean (passing the computed delay as a suggestion is a good call) and the _cancelReconnection abstraction is cleaner than the old timeout field. A few things to tighten up around the weaker cancellation contract that a user-supplied scheduler introduces:

Also: ReconnectionScheduler isn't re-exported from packages/client/src/index.ts — users can't import the type to annotate their scheduler implementation without reaching into the internal path.

packages/client/src/client/streamableHttp.ts

- guard reconnect() against late firing after close via aborted-signal check - wrap _cancelReconnection in try/finally so close() always aborts and fires onclose - wrap recursive _scheduleReconnection in try/catch to route scheduler errors to onerror instead of unhandled rejection - export ReconnectionScheduler type from package index - add tests for late-firing reconnect and throwing cancel function

bhosmer-ant

All four findings addressed — the abort-guard, try/finally in close(), try/catch around the recursive _scheduleReconnection, and the type export are all correct and minimal. Two new tests cover the edge cases (late-firing reconnect after close, cancel-throws-but-abort-still-fires). Bughunter ran clean (21 candidates, 0 confirmed). LGTM.

One pre-existing minor inconsistency (not introduced here, not blocking): the _scheduleReconnection call at ~line 438 (graceful-disconnect path) isn't directly wrapped like the one at 459 — but it's inside the outer try, so a throwing scheduler there gets caught at line 447 with a slightly misleading "SSE stream disconnected" message. Optional follow-up at most.

packages/client/src/client/streamableHttp.ts

…es.ts file

claude

LGTM

Extended reasoning...

Overview

This PR adds an optional reconnectionScheduler callback to StreamableHTTPClientTransportOptions, allowing non-persistent environments (serverless, mobile, desktop sleep/wake) to override the default setTimeout-based SSE reconnection. The change touches one source file (streamableHttp.ts), a new companion examples file, the package index re-export, and comprehensive tests.

Security risks

None. The change is additive — a new optional configuration callback. No auth, crypto, or permissions code is modified. The scheduler receives only a reconnect callback and delay/attempt metadata; it cannot access internal transport state.

Level of scrutiny

Medium. This is a well-scoped, non-breaking feature addition to a transport layer. All three reviewer suggestions from bhosmer-ant (abort guard in reconnect closure, try/finally in close(), try/catch around scheduler in .catch handler) have been incorporated and their comments resolved. My previous nit about the examples convention has also been addressed with a proper streamableHttp.examples.ts companion file. 8 new tests cover the scheduler, fallback, cancel, void-return, late-fire, and cancel-throws scenarios.

Other factors

Default behavior is unchanged (falls back to setTimeout)
Internal field rename (_reconnectionTimeout → _cancelReconnection) is private API only
Changeset included for minor version bump
Existing tests updated to use the new internal field name
No CODEOWNERS concerns for these files

bhosmer-ant

Re-approving after main merge + the .examples.ts companion file move (per repo convention). No functional changes to the scheduler code since my previous approval.

claude · 2026-03-27T17:09:56Z

packages/client/src/client/streamableHttp.ts

+        if (this._reconnectionScheduler) {
+            const cancel = this._reconnectionScheduler(reconnect, delay, attemptCount);
+            if (typeof cancel === 'function') {
+                this._cancelReconnection = cancel;
+            }


🟡 Nit: When the custom reconnectionScheduler returns void (no cancel function), _cancelReconnection is not reset to undefined, so it can retain a stale cancel function from a prior _scheduleReconnection call. The setTimeout path (line 360) always sets _cancelReconnection, but the scheduler path only sets it conditionally. Fix: this._cancelReconnection = typeof cancel === "function" ? cancel : undefined;

Extended reasoning...

When _scheduleReconnection is called and a custom reconnectionScheduler is provided, the return value is checked with typeof cancel === "function". If it is a function, _cancelReconnection is set. However, if the scheduler returns void, _cancelReconnection is left untouched — it retains whatever value it held from a previous call.

Compare this with the default setTimeout path, which unconditionally sets _cancelReconnection = () => clearTimeout(handle). The two branches have inconsistent behavior: one always updates the field, the other only conditionally updates it.

Step-by-step proof: Consider two SSE streams (GET + POST) that disconnect concurrently:

Stream A disconnects. _scheduleReconnection is called. The custom scheduler returns cancelA. Now _cancelReconnection = cancelA.

Before cancelA fires, Stream B disconnects. _scheduleReconnection is called again. This time the scheduler returns void (e.g., it delegates to a fire-and-forget platform API). Since typeof undefined \!== "function", the if branch is skipped. _cancelReconnection still holds cancelA — a stale reference.

On close(), this._cancelReconnection?.() calls the stale cancelA instead of having no cancel for Stream B's reconnection. Stream B's pending reconnection cannot be cancelled via this mechanism.

The practical impact is very low. The reconnect closure already guards against a closed transport with if (this._abortController?.signal.aborted) return (line 343), so a late-firing reconnect after close() is safely no-oped. Calling a stale cancel function is typically harmless (a no-op on an already-fired callback). The scenario also requires specific concurrent stream timing that is uncommon in practice.

The fix is a one-line change to unconditionally assign _cancelReconnection:

this._cancelReconnection = typeof cancel === "function" ? cancel : undefined;

This maintains the invariant that _cancelReconnection always reflects the currently scheduled reconnection, consistent with the setTimeout path.

bhosmer-ant

Good catch on the void-return edge case — when _scheduleReconnection is invoked from _handleSseStream (not via the reconnect closure which pre-clears), a void-returning scheduler would leave the previous cancel stale. The always-set ternary is the right fix. LGTM.

felixweinberger requested a review from a team as a code owner March 25, 2026 21:26

felixweinberger mentioned this pull request Mar 25, 2026

feat: add custom reconnection scheduler for non-persistent environments #1177

Closed

9 tasks

claude bot reviewed Mar 25, 2026

View reviewed changes

felixweinberger requested a review from mattzcarey March 25, 2026 21:36

bhosmer-ant requested changes Mar 25, 2026

View reviewed changes

packages/client/src/client/streamableHttp.ts Show resolved Hide resolved

packages/client/src/client/streamableHttp.ts Outdated Show resolved Hide resolved

packages/client/src/client/streamableHttp.ts Outdated Show resolved Hide resolved

bhosmer-ant previously approved these changes Mar 27, 2026

View reviewed changes

Merge branch 'main' into fweinberger/reconnection-scheduler

d18c9b3

claude bot reviewed Mar 27, 2026

View reviewed changes

packages/client/src/client/streamableHttp.ts Show resolved Hide resolved

docs(client): move ReconnectionScheduler example to companion .exampl…

b12a469

…es.ts file

felixweinberger dismissed bhosmer-ant’s stale review via b12a469 March 27, 2026 14:32

claude bot reviewed Mar 27, 2026

View reviewed changes

bhosmer-ant previously approved these changes Mar 27, 2026

View reviewed changes

Merge branch 'main' into fweinberger/reconnection-scheduler

3ac7bb4

claude bot reviewed Mar 27, 2026

View reviewed changes

fix(client): reset _cancelReconnection when scheduler returns void

6e24e54

felixweinberger dismissed bhosmer-ant’s stale review via 6e24e54 March 27, 2026 19:54

bhosmer-ant approved these changes Mar 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(client): add reconnectionScheduler to StreamableHTTPClientTransport#1763

feat(client): add reconnectionScheduler to StreamableHTTPClientTransport#1763
felixweinberger wants to merge 6 commits intomainfrom
fweinberger/reconnection-scheduler

felixweinberger commented Mar 25, 2026

Uh oh!

changeset-bot bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

claude bot left a comment

Uh oh!

felixweinberger commented Mar 25, 2026

Uh oh!

bhosmer-ant left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bhosmer-ant left a comment

Uh oh!

Uh oh!

claude bot left a comment

Uh oh!

bhosmer-ant left a comment

Uh oh!

claude bot Mar 27, 2026

Uh oh!

bhosmer-ant left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

felixweinberger commented Mar 25, 2026

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

changeset-bot bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Overview

Security risks

Level of scrutiny

Other factors

Uh oh!

felixweinberger commented Mar 25, 2026

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Overview

Security risks

Level of scrutiny

Other factors

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

claude bot Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Mar 25, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 25, 2026 •

edited

Loading